{
    title:  'Hosting in Appweb',
    crumbs: [
        { "User's Guide": 'index.html' },
    ],
}
            <h1>Hosting ESP in Appweb</h1>
            <p>ESP applications can run stand-alone via the <em>esp</em> utility command. Alternatively, they
            can be hosted in the Appweb web server as part of a broader set of web services and content.</p>

            <p>ESP is included by default in Appweb. However, Appweb can be configured and built to exclude ESP.
            If you have trouble activating ESP in Appweb, ensure it was included in your build of Appweb.</p>

            <a id="app"></a>
            <h2>ESP Applications</h2>
            <p>ESP applications hosted in Appweb are still are configured via their <em>esp.json</em> file. 
            However, Appweb manages the listening endpoints, user accounts, logging and properties defined in
            the <a href="config.html#server"><em>http.server</em></a> collection of the <em>esp.json</em> file.</p>

            <p>For more information, please read <a href="config.html">Configuring ESP</a> and the relevant sections of the
            <a href="https://embedthis.com/appweb/doc/users/configuration.html">Appweb Configuration Guide</a>
            before reading this document.</p>

            <h3>Defining ESP Applications</h3>
            <p>To define an ESP application in Appweb, use the <em>EspApp</em> directive in your <em>appweb.conf</em> file. 
            This directive takes the following arguments:</p>

            <code class="inverted">EspApp prefix="URI" config="path/to/esp.json"</code>

            <h3>Compiling</h3>
            <p>When compiling ESP applications to be hosted in Appweb, you must use the <em>appweb-esp</em> command instead
            of <em>esp</em>. This is because you must link with the Appweb libraries when compiling ESP applications.</p>

<!--
            <p>This defines an ESP application at the given directory that will receive 
            requests that begin with specified URI prefix. </p>

            <a id="controllers"></a>
            <h2>ESP Controllers</h2>
            <p>ESP Controllers may be used as part of an ESP application or they may be used stand-alone outside
            an ESP app. A stand-alone controller must define a route that specifies the desired URI, the source file
            containing the controller and the format of the URI to action mapping. For example:</p>
            <code class="inverted">
&lt;Route ^/greetings/{action}$&gt;
    SetHandler espHandler
    Source     greetings.c
    Target     run greetings-$1
&lt;/Route&gt;
</code>
            <p>This defines a controller in <em>greeting.c</em> to respond to URIs that begin with <em>/greetings</em>.
            <p>Controllers are dynamically loaded and reloaded as required. Controllers contain one or more actions and have
            a module initialization routine that defines the actions for ESP to support. For example:</p>
<code class="inverted">
#include "esp.h"
static void hello() {
    render("Hello World\n");
}
ESP_EXPORT int esp_controller_app_greetings(HttpRoute *route) {
    espDefineAction(route, "greetings-hello", hello);
    return 0;
}
</code>
            <p>This defines a single action which renders the string "Hello World\n" in response to the client request 
            for the URI <em>/greeting/hello</em>. When the URI is requested, the controller is compiled, linked into
            a dynamic library, saved in the cache directory and loaded into Appweb. If the source is modified, the 
            old controller is unloaded (after ensuring there are no active requests) and the new source is compiled and
            loaded.</p>

            <p>If you wish to pre-compile the controller, use the <em>esp</em> utility program. For example:</p>
            <code class="inverted">esp compile greetings.c</code>
-->
